%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{ 2018/07/10}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpclink}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpclink}

\Prog{hpclink} is used to link \textbf{HPCToolkit}'s performance measurement library (\HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}}) into a  statically linked application.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

\Prog{hpclink} \oOpt{options} \Arg{link-command}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

\Prog{hpclink} is a wrapper around the system linker
which injects the HPCToolkit performance measurement library
when statically linking an application.
If your application is statically linked you must use \Prog{hopclink} at link time
instead of \HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}} at run time
because \Prog{hpcrun}'s dynamic mechanism for injecting the library
only works for dynamically linked applications.
Although using \Prog{hpclink} does require changing your link step,
it does not require changes to your source code
or to the way you compile individual files and libraries.

To link with \Prog{hpclink}, first locate the last step in your application's build system
(the command that produces the final, statically linked binary).
Then just use \Prog{hpclink} instead of the system linker in that command.
One simple way of accomplishing this is to prepend \Prog{hpclink} to your makefile's link line.
You may also wish to rename your binary (e.g. \texttt{-o }\emph{appname}\texttt{-hpclink}}).

To control HPCToolkit's performance measurement during application execution,
set one or more of the following environment variables:

\begin{itemize}
\item \verb+HPCRUN_EVENT_LIST=<event1>[@<period1>];...;<eventN>[@<periodN>]+\\
  Sample using \Arg{event1} through \Arg{eventN} with their associated periods.
  Corresponds to \Prog{hpcrun} option \Prog{-e}~/~\Prog{--event}.

\item \verb+HPCRUN_TRACE=1+\\
  Enable tracing, i.e. collection of data for \Prog{hpctraceviewer}.
  Corresponds to \Prog{hpcrun} option \Prog{-t}~/~\Prog{--trace}.

\item \verb+HPCRUN_PROCESS_FRACTION=<frac>+\\
  Measure only a fraction \Arg{frac} of the execution's processses.
  For each process, enable measurement with probability \Arg{frac},
  a real number or fraction between 0 and 1.
  Corresponds to \Prog{hpcrun} option \Prog{-f}~/~\Prog{-fp}~/~\Prog{--process-fraction}.

\item \verb+HPCRUN_OUT_PATH=<outpath>+\\
  Corresponds to \Prog{hpcrun} option \Prog{-o}~/~\Prog{--output}.

\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Arguments}

\begin{Description}
\item[\Arg{link-command}] The link command for producing a statically linked application binary.
It typically has the following form:\\
\SP\SP\SP \Arg{compiler} \Arg{[link-options]} \Arg{object-files} \Arg{libraries}
\end{Description}


\subsection{Options: Informational}

\begin{Description}

\item[\Opt{-v}, \Opt{--verbose}]
Emit verbose messages: display both the original and the modified link command lines.

\item[\Opt{-V}, \Opt{--version}]
Print version information.

\item[\Opt{-h}, \Opt{--help}]
Print help.

\end{Description}


\subsection{Options: Linking}

\begin{Description}

\item[\Opt{-dw}, \Opt{--double-wrap}]
Double quote the linker wrap options introduced by \Prog{hpclink},
i.e.emit \Prog{-Wl,-Wl} instead of \Prog{-Wl}.
Use this to work around problems with the Berkeley UPC compiler script (rarely necessary).

\item[\OptArg{-fe}{dir}, \OptArg{--front-end}{dir}]
In a cross-compile link,
use the current install tree for back-end libraries and
use \Arg{dir} for the install directory (prefix) of front-end tools (\Prog{hpcfnbounds}).

\item[\Opt{--io}]
Include a library to track and report the number of io bytes read and written.

\item[\Opt{--ga}]
Include wrappers for the Global Arrays library.

\item[\Opt{--memleak}]
Include HPCToolkit's memory leak detection libraries.

\item[\OptArg{--plugin}{name}]
Add the libraries and wrapped symbols specified by plugin \Arg{name} in the plugins directory.

\item[\OptArg{-u}{symbol}, \OptArg{--undefined}{symbol}]
Pass \Arg{symbol} to the linker as an undefined symbol.
This option is rarely needed,
but if \Prog{hpclink} fails with an undefined reference to \texttt{\_\_real\_foo}
then the option ``\texttt{-u foo}'' may induce the linker to correctly link this symbol.
May be used multiple times.

\end{Description}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}

Compile the "hello, world" program with \Prog{gcc} and link in the
\Prog{hpcrun} code statically.

\begin{verbatim}
    hpclink gcc -o hello -g -O -static hello.c
\end{verbatim}
%
Link an \Prog{hpcrun}-enabled application from object files and the
math library.

\begin{verbatim}
    hpclink gcc -o myprog -static main.o foo.o ... -lm
\end{verbatim}
%
Make both native and \Prog{hpcrun}-enabled versions of an application from object files and system libraries with the \Prog{mpixlc} compiler.
Note that the argument list to the \Prog{hpclink} command is exactly the command to build the native version except for the name of the output file.

\begin{verbatim}
    mpixlc -o myprog main.o foo.o ... -lm -lpthread
    hpclink mpixlc -o myprog.hpc main.o foo.o ... -lm -lpthread
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Launching Static Programs}

For dynamically linked binaries, the \Prog{hpcrun} script is used to launch programs and set environment variables, but on systems with separate compute nodes, this is often not available.
In this case, the \texttt{HPCRUN\_EVENT\_LIST} environment variable is used to pass the profiling events to the \Prog{hpcrun} code.

\begin{verbatim}
    export HPCRUN_EVENT_LIST="PAPI_TOT_CYC@4000000"
    myprog arg ...
\end{verbatim}
%
For example, on a Cray XT system, you might launch a job with a PBS
script such as the following.

\begin{verbatim}
    #!/bin/sh
    #PBS -l size=64
    #PBS -l walltime=01:00:00
    cd $PBS_O_WORKDIR
    export HPCRUN_EVENT_LIST="PAPI_TOT_CYC@4000000 PAPI_L2_TCM@400000"
    aprun -n 64 ./myprog arg ...
\end{verbatim}
% $ Artificially end math mode.
%
The IBM Blue Gene system uses the \texttt{--env} option to pass
environment variables, so you might launch a job with a command
such as the following.

\begin{verbatim}
    qsub -t 60 -n 64 --env HPCRUN_EVENT_LIST="WALLCLOCK@1000" \
        /path/to/myprog arg ...
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Notes}

The command line passed to \Prog{hpclink} must produce a statically linked binary and the \Prog{hpclink} script will fail if it does not.

With some compilers, e.g. IBM's XL family,
interprocedural optimization interferes with \Prog{hpclink} and causes failure.
If this occurs interprocedural optimization must be disabled.
All other optimizations can remain enabled.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.\\
\HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2019, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
Mark Krentel \\
Rice HPCToolkit Research Group \\
Email: \Email{hpctoolkit-forum =at= rice.edu} \\
WWW: \URL{http://hpctoolkit.org}.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:
